{smcl}
{* 20 August 2002/23 April 2008}{...}
{cmd:help labmask}{right: ({browse "http://www.stata-journal.com/article.html?article=gr0034":SJ8-2: gr0034})}
{hline}

{title:Title}

{p2colset 5 16 18 2}{...}
{p2col :{hi:labmask} {hline 2}}Assign values or value labels of one variable as value labels to another{p_end}
{p2colreset}{...}


{title:Syntax}

{p 8 17 2}
{cmd:labmask} 
{it:varname}
{ifin}{cmd:,} 
{cmdab:val:ues}{cmd:(}{it:valuesname}{cmd:)} 
[{cmdab:lbl:name}{cmd:(}{it:lblname}{cmd:)} 
{cmd:decode}] 


{title:Description}

{p 4 4 2}{cmd:labmask} assigns the values (or optionally the value
labels) of one variable {it:valuesname} as the value labels of another
variable {it:varname}.  Any existing value labels will be overwritten.
The idea behind the program name is that henceforth the face that
{it:varname} presents will not be its own, but a mask borrowed from
{it:valuesname}. Thus, for example, a year variable might be coded by
party winning at election and those value labels then shown as labels on
a graph axis. 

{p 4 4 2}{it:varname} must take on integer values for the observations
selected. {it:valuesname} must not vary within groups defined by the distinct
values of {it:varname} for the observations selected. However, there is no rule
that the same label may not be assigned to different values of {it:varname}. 


{title:Options}

{p 4 8 2}{cmd:values(}{it:valuesname}{cmd:)} specifies a variable whose
values (by default) or value labels (optionally) will be used as the
value labels of {it:varname}. {opt values()} is required. 

{p 4 8 2}{cmd:lblname(}{it:lblname}{cmd:)} specifies that the value
labels to be defined will have the label name {it:lblname}. The default
is that they will have the same name as {it:varname}. Any
existing value labels for the same values will be overwritten in either
case. 

{p 4 8 2}{cmd:decode} specifies that the value labels of {it:valuesname}
should be used as the value labels of {it:varname}. The default is to
use the values of {it:valuesname}. 


{title:Remarks}

{p 4 4 2}For an explanation of the use of {cmd:labmask} in conjunction with
{cmd:seqvar}, which is also installed with this command, see 
{helpb seqvar}. 
 

{title:Examples}

{p 4 8 2}{cmd:. egen order = rank(-mpg), unique}{p_end}
{p 4 8 2}{cmd:. labmask order, val(make)}{p_end}
{p 4 8 2}{cmd:. label var order "Make and Model"}{p_end}
{p 4 8 2}{cmd:. tabdisp order, c(mpg)}{p_end}
{p 4 8 2}{cmd:. tabdisp order foreign, c(mpg)} 


{title:Author} 

{p 4 4 2}Nicholas J. Cox, Durham University, U.K.{break}
n.j.cox@durham.ac.uk


{title:Also see}

{psee}
Article: {it:Stata Journal}, volume 8, number 2: {browse "http://www.stata-journal.com/article.html?article=gr0034":gr00.0}{break}

{p 4 13 2}Manual:  {hi:[D] label}  

{psee}Online:  {manhelp label D}; {help limits}; {helpb seqvar}, if installed
{p_end}
